Skip to content

DEV-1070: decode a GSR code below the reference as open on every range - #307

Merged
JongChern merged 1 commit into
masterfrom
DEV-1070_gsr_below_reference_reads_open
Oct 1, 2026
Merged

JongChern merged 1 commit into
masterfrom
DEV-1070_gsr_below_reference_reads_open

Conversation

@marknolan

@marknolan marknolan commented Sep 26, 2026 •

Copy link
Copy Markdown
Member

DEV-1070. Stacked on #305 (DEV-1067); it targets that branch, so the diff is this change only.

Explainer: before/after charts for DEV-1067, DEV-1068 and DEV-1070, and a table of the sibling PRs across every host API: https://claude.ai/artifact/6hDc2Ue9hdF8gcUDZXzFts (Shimmer sign-in)

Problem

The GSR amplifier equation, R = Rf / (V/Vref − 1), has no positive solution at or below the amplifier's reference. No skin resistance can pull the output under it, so a code there means the electrodes are open. Range 3 has long raised such a code to its open-circuit limit (683, or 1138 on gen-2 since #305). Ranges 0–2 did not, and in auto-range they see these codes too. When the electrodes come off, the device climbs one range at a time, and the firmware repeats the sample that triggered each switch through the 80 ms settling time, tagged with the range it was measured on. The equation gives those samples a negative resistance, which nudgeGsrResistance floors at 8 kΩ (ASM-2156). The result is 125 µS, the highest conductance the device can report, for an open circuit. On a fixed range they read the bottom of the window.

Real data has them. DEV-793 B6 (ASM_PC Test_056, SR68-9) has 50 such samples, read from the raw range bits:

  • at the start of the recording, with the electrodes open: range 0 at codes 0 and 1131, range 1 at 1131, range 2 at 1132
  • as the 33 kΩ load comes off: range 1 at 1137

The reference output reads all 50 as 125.000 µS.

Fix

SensorGSR.calibrateGsrDataToKOhmsWithOpenCircuitLimit decodes any code below the front end's limit as range 3 at the limit, whatever range it was measured on. Both decode paths call it: SensorGSR.processDataCustom (Verisense, and the Shimmer3 and GQ sensor classes) and the legacy Shimmer3/GQ path in ShimmerObject.

  • An open circuit reads the same on every range as the settled range 3 does: about 4.0 GΩ on gen-2, and 4.5 GΩ on the Shimmer3, the GQ and the SR62.
  • A fixed range still clamps to its own window, so there an open circuit now reads the top of it instead of the bottom.
  • Only resistance and conductance change. The range channel and the uncal values are as before.
  • Both limits are the first code above 0.5 V, so the rule moves exactly the codes that decoded to a negative resistance: the samples ASM-2156's floor already moved. No valid reading changes, on the Shimmer3 or anywhere else. Nothing decodes below 8 kΩ any more, so the floor is now only a backstop.

Tests

API_00019_GsrBelowReferenceReadsOpen checks:

  • the helper on all three front ends, over every code and range
  • that exactly the codes that decoded negative change
  • that auto-range never reaches the floor
  • through processDataCustom: Test_056's codes on an SR68-9 and an SR61-5, the SR62, fixed ranges, the Shimmer3 and the ShimmerGQ
Rule Result
disabled 8 of 9 fail (125 µS, and 8 kΩ on fixed range 0)
this PR 9 of 9 pass; the whole ShimmerDriver suite passes (117 tests)

CI builds only ShimmerDriverPC, so it will not run this test; it was run locally. It is numbered 00019 because other branches use numbers up to 00018.

ASM_PC reference data

The references were regenerated with this branch as ASM_PC's submodule, on local copies of the test data. The harness parses in place in the SharePoint folders, so SharePoint was not touched. A baseline run on ASM_PC main passes all 22 GSR tests. On this branch five change, and every change is 125.000 → 0.000 µS in a GSR_CAL file:

Test Rows changed From
ASM_PC_00005 Test_056 3255 3205 #305 (range 3), 50 this PR
ASM_PC_00005 Test_053, Test_057 6 each (rows 1–6) this PR
ASM_PC_00009 ASM_1802 6 in each of 3 files this PR
ASM_PC_00009 ASM_2156 15 this PR

The uncal CSVs are unchanged. Rows 1–6 are the first six samples of a recording, which the firmware fills with one repeated value. They are raised as a separate firmware question on the ticket. With the eight regenerated files installed, all five tests pass.

After merge

  • ASM_PC: bump this submodule, and replace the eight reference files (they are ready; see DEV-1070). RTC Recover Test_016 still needs a run, which needs test-credentials.properties.
  • Shimmer-MATLAB-ID: its VerisenseFileParserPC.jar gets this only when it is re-vendored.

Sibling PRs (same rule, same ticket)

🤖 Generated with Claude Code

The GSR amplifier equation, R = Rf / (V/Vref - 1), has no positive
solution at or below the amplifier's reference. No skin resistance can
pull the output under it, so a code there means the electrodes are
open. Range 3 has long raised such a code to its open-circuit limit (683,
or 1138 on gen-2 since DEV-1067). Ranges 0-2 did not, and in auto-range
they see these codes too. When the electrodes come off, the device climbs
one range at a time, and the firmware repeats the sample that triggered
each switch through the 80 ms settling time, tagged with the range it was
measured on. The equation gave those samples a negative resistance, which
the ASM-2156 floor turned into 8 kOhm: 125 uS, the highest conductance
the device can report, for an open circuit. On a fixed range they read
the bottom of the window.

DEV-793 B6 (ASM_PC Test_056, SR68-9 2511210195BC) shows it. Its raw
range bits put 50 such samples on ranges 0-2. At the start of the
recording there are range 0 at codes 0 and 1131, range 1 at 1131 and
range 2 at 1132. As the 33 kOhm load comes off there is range 1 at 1137.
The reference output reads all 50 as 125.000 uS.

calibrateGsrDataToKOhmsWithOpenCircuitLimit now decodes any code below
the front end's limit as range 3 at the limit, whatever range it was
measured on. Both decode paths call it: SensorGSR.processDataCustom
(Verisense, and the Shimmer3 and GQ sensor classes) and the legacy
Shimmer3/GQ path in ShimmerObject. Only the resistance and conductance
change. The range channel still reports the resistor in circuit, and
the uncal values are as before.

An open circuit now reads the same on every range as the settled range 3
does: about 4.0 GOhm on gen-2 (this driver divides by 0.5 V), and 4.5 GOhm
on a Shimmer3, GQ or SR62. A fixed range still clamps to its own window,
so there an open circuit now reads the top of it.

Both limits are the first code above 0.5 V. So the rule moves exactly
the codes that the equation decoded to a negative resistance, which are
the samples ASM-2156's floor already moved. Every other code decodes as
before, and none decodes below 8 kOhm, so the floor is now only a
backstop. That keeps ASM-2156's promise to Shimmer3 customers: no valid
reading changes.

API_00019 checks the helper on all three front ends, over every code and
range. It checks that exactly the codes that decoded negative change, and
that auto-range never reaches the floor. Through processDataCustom it
covers Test_056's codes on an SR68-9 and an SR61-5, the SR62, fixed
ranges, the Shimmer3 and the ShimmerGQ. With the rule disabled, 8 of its
9 tests fail: 125 uS, and 8 kOhm on fixed range 0. The ShimmerDriver
suite passes (117 tests).

Stacked on DEV-1067, without which gen-2's limit of 1134 itself decodes
negative. Replaying Test_056's raw words through this decode, which
reproduces the reference to the last digit, changes exactly those 50
rows, from 125.000 to 0.000 uS, on top of DEV-1067's 3205.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

@JongChern JongChern left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. test002 checks every code from 0 to 4095 on every range and front end, and only the codes that used to decode to a negative resistance change, so readings with skin contact are untouched.

CI hasn't run on this branch, because it targets #305's branch. I ran ./gradlew test in ShimmerDriver on 00a3f65: 117 tests, all passing, including API_00019 (9) and API_00015 (5).

Comments, none blocking:

  1. The legacy Shimmer3/3R/GQ path in ShimmerObject.buildMsg (Bluetooth streaming and SD logs) gets the same change, but no test drives it: test008 and test009 go through SensorGSR.processDataCustom. It's the same one-line call, so the risk is low. A test that pushes a below-reference GSR sample through buildMsg would cover the path most Consensys users hit.
  2. Same CI note as on #305: the description says CI won't run API_00019. It will, because gradle.yml runs the ShimmerDriver tests, once this PR targets master.
  3. After #305 merges, change this PR's base to master by hand (branch auto-delete is off, so GitHub won't), let CI run, then merge.

Base automatically changed from DEV-1067_gsr_range3_open_circuit_limit to master October 1, 2026 05:22
@JongChern
JongChern merged commit 73dcd41 into master Oct 1, 2026
@JongChern
JongChern deleted the DEV-1070_gsr_below_reference_reads_open branch October 1, 2026 05:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants